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Bootstrap Zero 


POSTS ARCHIVE 


Hi there 


You've reached the Bootstrap Zero blog, which was written during 
July 2015 for RetroChallenge 2015/07. 


If you keep reading down this page, you'll be reading the posts in 
reverse order, and they might not make much sense that way. 


It'd probably be better to read the archived version of this blog in the 
SITU-SOL repository, where you will also find continuation of this 


work, now and in future. 


Thank you for your interest in writing code by hand! 


1 note Oct 16th, 2017 


MORE YOU MIGHT LIKE 


Retrospective 


What have | learned from this? What would | do differently, if | had to 
do it all again? 


Writer’s cramp. | really didn’t forsee that. | probably should've, but | 
didn’t. My wrist seems OK now, but last week it was definitely a bit 
ache-y, and | scaled back my ambitions a bit because | didn’t want to 
stress it too much. | guess it’s been a while since I’ve written this 
much. 


Uneven columns of text. | wrote the “nice” version of the code on 
printer paper placed over lined paper, to keep my rows straight, but | 
really should’ve used graph paper instead, to keep my columns 
straight too. Or French ruled paper, or a ledger, or something. Also, 
putting more thought into choice of colours, etc., would’ve been nice. 


Assembler-ness in hand-assembly. | only flaunted the fact that | 
didn't have to please an assembler’s idea of syntax a little bit: | used 
the same “local labels” like NEXT: over and over again, since | knew 
very well which one | meant at each point. An assembler program 
would've wanted me to call them NEXT1, NEXT2 or whatever, to 
keep them apart. | even used underscores in these labels, purely out 
of habit, but of course they weren’t at all necessary. | could’ve even 
gone much further — | could’ve just drawn arrows from one part of the 
code to another. | kind of regret not doing something more “artistic” 
like that. 


No LEDs for the address lines. As | mentioned in the | love bits 
post, it would've saved a significant amount of debugging if | had 
known what address | was entering bits af. That's a definite 
advantage the nice big front-panel of the Altair 8800 has over the 
austere front-panel of the 1802 Membership Card. But even showing 


the lowest 8 bits of the address would’ve been useful as a guard 
against this sort of address-misalignment problem. 


No padding between routines. | hand-assembled each routine to 
start at the very next address available after the previous routine. My 
excuse was that | didn’t want to have to enter more bytes than | had 
to. But this is a risky practice, because it’s quite easy to miss an 
instruction, or to want to insert an instruction later, for debugging; but 
if there’s no free space after the routine, you need to figure out what 
to replace with a JMP to somewhere else in memory (which will JMP 
back to continue the routine), then you need to find somewhere else 
in memory to put it... it’s a mess. | was lucky in that | didn’t hit a 
problem that required this. But it was luck. It would’ve been smarter 
to add 3 or so NOPs after the end of each routine, to make adjusting 
the routine easier, if needed. Even if it would’ve meant entering 24 
more bits each time. 


No comments. Yeah, that’s the thing, see. Writing documentation 
by hand is harder than writing code by hand because documentation 
is... sentences. The fact that you're already writing out the 
“important” stuff seems like a good excuse to leave out the “non- 
critical” stuff like comments. But the comments are important — 
especially in assembly language, where it’s really important to define 
what each routine expects when it is called, and what the rest of the 
program can expect when it’s finished (preconditions and 
postconditions.) If you fail to pay attention to these when writing 
code that calls that routine, very bad things can happen. Most of my 
first drafts did include scribbled preconditions and postconditions, 
but those notes didn’t make it to the final listings. 


The language is a bit goofy. And incomplete (no real standard 
library.) Well, | kept going back and forth on whether | should make a 
FORTH-like language or a LISP-like language, while at the same 


time wanting to keep it as simple as possible... and eventually 
simplicity won out. The resulting design for SITU-SOL has some 
similarities to Shelta, which | suppose isn’t surprising. 


OK, those are the basic ones. But the big one is: 


A programming language alone does nota 
programming environment make! 


See, one reasonable way to interpret the goal of this project of writing 
code by hand, is to write enough code by hand so that you don't 
have to write code by hand anymore. 


But SITU-SOL doesn’t accomplish that goal. If you wanted to write a 
non-trivial SITU-SOL program... you'd probably want to write it out by 
hand first! 


( 


In other words... | probably should’ve just written a text editor 
instead. Maybe next year? 


Well, that’s not quite a fair assessment, either. Let me explain... 


In the modern world, we’d write our program in our text editor, and 
we'd assemble it with our assembler program, which is a separate 
thing. 


But uncompressed text takes up a fair amount of space, and on 8-bit 
machines, with their modest RAM and slow (or non-existent) 
persistent storage, that space is ata premium. So programming 
environments like BASIC do clever tricks like tokenizing the source 
code; an instruction like INPUT, even though it is entered as five 
characters, can be represented by one byte in memory, and 


displayed as those five characters again when the program is 
LISTed. Forth can do a similar trick (although | admit I’m not familiar 
with exactly how Forth is spec’ed to work, in this regard.) 


So, once | got SITU-MON in, | probably should’ve written a text 
editor, so that | could design and write and edit further programs 
directly on the computer, without using paper. 


But once | came across the idea that SITU-SOL’s code could be both 
compiled and tokenized (i.e., treat JSR $xxxx as a “token” that prints 
out the symbal-name just before $xxxx when it is decompiled, and so 
forth) — that’s pretty neat, and | felt | had to go in that direction. 
(Maybe that’s how Forth works, too. | should look that up.) 


Anyway... 


To achieve this “edit directly on the computer, avoid paper” plateau, 
there are at least 3 more things the SITU-SOL environment should 
do: 


e Let you list the symbals that have been defined so far. (Like 
Forth’s WORDS, but | guess it would be called $SYMBALS 
here.) 

e Let you see the contents of a symbal’s definition, in a human- 
readable format. 

e Let you change the definition of a symbal. Or, if you can’t do 
that directly, let you replace every call to one symbal, with a 
call to a different symbal, in every defined symbal. (Then 
instead of changing a symbal, you write a new symbal and 
replace all the calls to the old one.) 


Now, | did design SITU-SOL to support these things... and | have 
written code to do these things! | include it below, for completeness. 
But | don't think I'll have the time (or the wrist-stamina) to hand- 


assemble it and enter it before the end of the month. 


The code for $SYMBALS: 
SYNBALS « 
pieRPS : DSR  RESET_STAB 
SR = RESET_LINE 
Lot?: JSR PEEK_svAG 
BNE comr 
BRP OUTPUT UN_TTy 


CONT: 


WAIL Si4B Nan : 


SET: 


TSR 
Ome 


JSR 
AND 
BNE 
JSR 
JSR 
Jee 
TSR 
OSR 
JSR 
ISR 
RYs 


WRITE _S VAB_ UAME 
Loop 


PEFK_SASB 

#4 30 

SET 

WRITE_ CHAR 

\N CK stas_pPte 
WRITE _STAB_ NAME 
INCR 

PEEK 

ADD. A_S*45 

ICR 


<— define 4 
SuPer 
$SYHBALS 
which Rs thes 


Dumping the contents of a symbal: 


WATE. Stace : LOA #dYay¥ 
“JSR WRITE. HR 


assames STAB_VTR \s at begeanny ok payleal of Symbol te dump 
DUMP SYMbAL: = TR REA SWEAR, 


cue Gag 7 ; 
. —— BWE svexr 
—_ ; ba WH 


JR WRITE-CHAR 
| . JsR WER StHS_eTR 
TSR READ_stas 
ee Ss, ae 
TMP WRITE. Space | 
wext: eff #$EA 
BeE NEXT 
aire La #? | 
JR WRTE_cHsR 
nal 7 LoA #3 : 
PO SSR ADD ALStAR | 
eee Yne WRiTe-srace | 
a ‘NExt: we #S Dg 


SNE GIRROR 
JGR INCR - RTS ; 
T5@ READ. —— ERRoR=  LPA FQ 
STA ARAL er oMe WRITE_cHyR 
JsR WOR 
Ten READ f 
- STA ARM 
aR BBR SR 
SR weR 


Tee WRIVE Stace 


PRW SYM (a ARG * GR SAVE_VHR PTR 
By CoPY _ ARG=To_ST4B_PIR 
Loa #2 
STA SB. pELTA 
JSR SUG_STAB_-PTR 
JSR RE,O_¢ 148 
Am #$7F 
STA S48_DELTA 
J5R SvuB_S™|HBb_prtR 


Cy Loop: TSR REAV_sSTAB 
eal AND #$39 
ii BNE Ewo 


TSR = READ_514B 


JSR WRITE CHAR 
JsR wer STAB 


JMP Loop 
END: "SR gestore _sta6_v re 
RTS 
SAVE Stas : COPY. ARG -To-STAB : 
LDA STU6_PTR_ ve LDA ARGQ_Lo 
PHA ST  STAB_PtR_LO 
Loa Lt LOA _H/ 
PHA STA abil 
RESTAE: 
PLA 
cA * “ul 
PLA 
STA “ “Le 


Replacing all calls to symbal1 with calls to symbal2: 


GB EQ in, 
SeneHenTs 


oF am SYABAL To 


ag ° TCO | AG_PTR 
pelnts do begianrns oP — 

—— Cones Cr AGG nth symbal 

BEQ REPLmE TRY 

Loa #093 


> JSR ADO Fr_STAB_PTR 


_ ew st MATCH: eee toa ef —__ 
snk =PEEK_STAB eee 


4 MATCH 


Same precondihens abest ARC. and NEW ws REPLACE CALLS 


KEPAGE Ave _catcs : JSR RESET_STAS, PTR 
Low: JSR PEEL STAS 


BNE ConT 
RTS 
Copr: TSR = REPLACE caues 
oMp = Loop 
CMD. REPLACE _ CALLS: TSR LookvP_SymBAL 
Bes FAte 


LpA STAB_PTR_LO 
STA ARGQ_LOTR-Lo 


LDA ~H( 

STA _H( 

JSR LookuP _SsymBAL 

Bes FAIL 

LbA Swe _L6 

STA N@&/ -LO 

LDA _u4 

5TA ~H{ 

SMP REPLACE. ALL_ CALLS 
FAIL : IMR REPORT_ERRoR 


Calling those last two routines from the interactive prompt, with /D 
SYMBAL to dump and /R SYMBAL1 SYMBAL2 to replace calls to 
symbals: 


CMD _ DOAP_ S¢pdat: 


SLASH_ CMDS: 


ME xT: 


N@yT: 


LOdkuP_SYm@AL 
RESET_Liwe 
bumP_ syMBAL 
OUTPOTLN_TTY 


hes 
‘2 ‘o1 


(we |F WE Mwew Fae / ) 
READ. CH4aR 


#4 °>D 
NEXT 
CMD_ Dume_symBA L 
#°R 
NExy 
CMD_ REPEAEE calc s 
REPORT_SRRIR FS _changs +o 
Contina ating tow 


expanded vevsun 


So, if the point of this project was to write the code by hand, | can 
indeed say | have written those routines by hand! Not assembled, 
entered, or tested... but written, yes! 


Future work 


I've created a Mercurial repository on Bitbucket, which is mirrored in 


a git repository on Github, where I'll be placing the support materials 


and binary images from this project, and maybe in the future... other 
stuff, like a disassembly of the code that was entered. 


One of the reasons | entered SITU-MON at $8100 was because 
when the Commodore 64 is booted with an 8K cartridge attached, 
that ROM appears at $8000. | didn’t start right at $8000 because | 
wanted to reserve room for the header (the bit of ROM that tells the 
C64 “yes, this is a cartridge”) and some routines to do some 


initialization. 


So, one thing I'd really like to do is make such a binary image. Even 
if only to use it in the emulator. Because it'd be kind of cool to boot 
the machine directly into SITU-SOL. But that’s a bit outside of the 
scope of this RetroChallenge project. 


But after July ends.... who knows? 


1 note 


SITU-SOL 


SITU-SOL. 


THE DIFFERENCE BETWEEN A “Low-Levet” 
PROGRAMMING LANGUAGE AND A “HIGH- LEVEL" 
ONE '§ NOT CLEAR-CUT, BUT ONE THING 
THAT MOST “HIGH-LEVEL" LANGUAGES Do 
IS TO AlLLow THE PROGRAMMER To 
DEFINE THEIR OWN IDENTIFIERS USING 
A (Mostey) FREE GHolcE oF LETTERS 
AND NUMBERS. IMPLEMENTING ‘THIS 
FEATURE MEANS STORING THESE SYMBALS* 
IN A DATA STRUCTURE, AND RETRIEVING 
THEM FROM “THIS STRUCTURE AS WELL. 
WE'LL IMPRoviSE A SYMBAL ~ ORIENTED 
LANGUAGE ARouND THIS, AND CALL IT: 
S(TU-SOL. 


wrmopucrion of te Eg 
=\CTION AND AOVENTURE Be 


SYNTAX OF SITU-SOL 


A SITU-SOL PROGRAM CONSISTS OF A 
NUMBER oF LINES, WHICH MAY BE ENTERED 
INTERACTIVELY. THE FIRST CHARACTER OF EACH 
LIVE HAS A SPECIAL MEANING: 


L symbal symbal - symba] 


— ComPILE THE SYMBALS Teo 
THE COMPILATION BUFFER. 


] Symbal 
- DEFINE A NEW SYMBAL, 
USING THE CURRENT contents 
OF THE ComPiL. BUFFER. 
-_ - RESERVED FoR FUTURE Exe. 
2 — QUIT SITU-sot (AND RETURN 


To SITU-MON, IF ApPLICAGCE) 


1F THE LINE BEGINS WITH ANY OTHER 
CHARACTER, tT 1S NOT SPECIAL, IT tS SIMPLY 


Symbal suyumbal ... symbal 


THESE SYMBALS ARE COMPILED To THE BurFEeR 
AND IMMEDIATELY EXECUTED CIMMEDIATE MoPE.) 


COMPILATION OF SYMBALS 


SOME SYMGBALS ARE SPECIAL FORMS WITH 
SPEC AL MEANINGS: 


HE xy = READ xy AS A BYTE (Tuo 
HEXADECIMAL DIGITS) AND LOAD 
THAT BYTE INTO THE A(CUMULATEA. 
2 symbal - EXECUTE THE NEXT SyMBAL 
ONLY IF THE ZERe FLAG IS 
NoT Ser. ("iF") 


symbal | - EXECUTE THE PREVIoUS SYMBAL 
AGAIN (AND AGAIN...) IF THE 
ZERo FLAG IS Not SET. 
(“ REPEAT") 


SYMBALS BEGINNING WITH < OR > HAVE A 
SPECIAL MEANING WHICH I$ RESERVED. 


OTHERWISE, THE SYMBAL IS LOOKED UP IN THE 
SYMBAL “TAGLE, AND THE DEFINITION AssoctATED 
WITH “THAT SYMBAL (S EXECUTED, IE THE SYMBAL 
COULD NOT BE FOUND IN THE SYMGAL TALE, 
THAT'S A COMPILATION ERROR. 


STANDARD SYMBALS 


WE WILL NEED A SET OF PRE-DEFINED 
SYMBALS IN ORDER To Do ANYTHING |NTERESTING 
IN THIS LANGUAGE. 


UNFORTUNEATELY, } HAVEN'T REALLY WORKED OUT 
WHAT THAT SET witt BE, YET. 


WELLE DEFINE SOME SIMPLE AD-HOC SYMGALS For 
TESTING PURPOSES LATER ON... 


FoR NOW, PLL NOTE THAT WE Could DEFINE A 
SET OF SYMBALS THAT OPERATE OW A STACK, 
MAKING THE LANGUAGE VAGUELY FORTH-LIkE. 


OR, IF WE DEFINE A TAPE-LIKE STORAGE 
FACILiTy, AND HAVE SYMBALS LIKE: 


$LEFT 

RIGHT 
CMP 
NOT 

¢ WRITE 


... THEN WE OUGHT To BE ABLE To Co0E 
ANY TURING MACHINE IN SITU-SoL, MAKING 
THE LANGUAGE ‘TURING- COMPLETE, 


[MPLEME NTATION NOTES. 


THE SAL TARE ean At $a 


a oni DEFINITION OF SYMBAL 
) = CMACHINE CODE ) 
— LENGTH OF DEFINITION 


- NUMBER oF CHARICTERS 
IN SYMBAL, W/HIGH GIT SET 
ASCIL CHARACTERS OF 
a | 


COMPILING A  SYMBAI 1S = BY write A JSR 
TO THE FIRST BYTE OF THE DEFINITION OF THE 
SYM ARAL. “Hid alll afb axennee , THE NAME 
CAN BE RECOVERED BY: 


ee Tost aun “LEN po gy FRoe 


THERE ARE THE FollLowiINQ® FURTHER RESTRICTIONS oN 
THE MACHINE- CODE DEFINITION OF A SYMBAL: 


IT MUST CONSIST OF 3n7\ BYTES, WHERE » IS 


AN INTEGER (WON-NEGATIVE, OF CouRSE) AND THE LAST 
BYTE 1S $6¢ (RTS). 


* ANY SYMBAL WH°9SE NAME BEGINS WITH JHE 
CHARACTER ‘$°> WILL NOT BE DECOMPILED oR 
RELOCATED BY THE SYSTEM (THESE ARE PRE-DEFINED 
“SYSTEM SYMBALS -) 


THE FIRST RESTRICTION 18 50 THAT IT?S Easy Te 


DECOMPILE A SYMBAL (Le. TREAT THIS AS BoTH CoMPILED 
AND TOKENIZED CoDE,) WE CoMPILE EACH SYMBAL OR 
SPECIAL FoRM To A MACHINE-COoDE |NSTRYCTION, AND 
PAD 1T To 3 BYTES WITH NOP?S. WHEN DECOMPILING, 
WE Look FoR 3-BYTE SEQUENCES THAT WE GENERATED 
AND TRANSLATE THEM TO TEXT. 


“THE SEConD RESTRICTION IS So THAT WE CAN HAVE 
SYMBALS THAT VIOLATE THE FIRST RESTRICTION, FOR 
EXAMPLE , CONTAINING JSR’S To MACHINE-CODE RoUTINES 
ELSEWHERE IN MEmoRY. BECAYSE THESE RovTINES 
ARE NOT IN A SYMBAL TABLE, DECOMPILATION Wourd 
PRoovcE GARBAGE WHEN IT TRIED To FIND OUT 
THEIR NAMES AND PRINT THEM. 


Now, the program listing! No, wait — | don’t want you to get the 
impression that this just appeared fully-formed on paper. So, first, I'll 


ask you to imagine about 30 sheets of paper that looked something 


like this: 


MATCH word : 


|LD 
LOK 
| VCP 


Lt to cy BEX 
f* a2 


CMe 


INX- 
LL ome 


a4 
| RA 


stable DICT_PIR ova b 
TR the 


| petate ot the 


vIN&,) x { | 
(Ome | MigeMatsH 
inek_ pier eTR (7 


ol 


A 


ceturn with 


OK, now the program listing! 


| 


cA 


Ir dhe Joken does 
advance DICT 
and eave Liwe | OFF AS na was. 
LINIEL loft ISS Lok dwg. 
SPACE | 23¢ Lo. Line AK 
LINE, x | | Cup tag 
PAST stoves} | ee MATCH | 
Dnr-psth,Y cue + 9D_ 


PHA usp 
AND #8 
BNZ CHECK, oT U 
PLA 

cme LINE |X 

BNE CHAR _ MISMATCH 
JSR WER rcT_PTR 
| INK 
> OMe 


INE - one t+ gut 


| Bea 


pale: DICT. FIR, LIVE. OFF, CARRY Hag. 


LDA) cE] x | 
CMP +g | 


BEQ MAqH -—+—+— 


tnp 450 

MATCH | 
Loy 4d 
LD 


Aud #¢9 | 


0 


TS 


AND L 
TAX 


pid 


token xt LINE OFF matches the werd at DICT_PTR, 


RY clear and | DICT_PTR “eth 
leatry gize byte of the did | entry. 


Also advance LINE_OFF to Yre| space, beyond the Soken. 
not mall, return) with CARRY set, 
LeTR beyand the fe entry (je. do the newt entry) 
Hecate’ A om he Palloue 4 by a Space» 


| 
(Dict_PaR)Y 


BA Z |SkiIeL ENTRY 
INCR DCTP TR 


te veeste 


LDA (DICT-PiR), 


a 


A 


or 


a hs Pp. 7 DictPrk 


RESET_ STAB_PTR: 


INCR _STAB_ PTR: 
ADPLA_STAB_P TR: 


ADD_TO.STAB_PTR: 


SUB_ STAB_PTR: 


LDA #$90 
STA STAB-PTR.LO 


LDA #$64 
STA STAB_PTR- HI 
RTS 


LDA #341 
STA STAB DELTA 


cle 

LDA STAB_PTR_LO 
ADC STAB_DELTA 
STA STAB_PTR-LO 
LOA STAB_PTR_HI 
Avc #$¢¢ 

STA STAB_PTR-HI 
RTS 


SEC 

LDA STAB_PTR.LO 
SBC STAB_DELTA 
STA STAB_PTR_LO 
LDA STAB_PTR-HI 
SBC #$ 06 

STA STAB_LPTR-H| 
RTS 


$329 PEEK_STAB: LDY #$9¢ 


2 LDA 
E RTS 
$330  WRITE_STAB: LDY 
0. STA 
| MP 


$337 LOOKUP_SYMBAL: JSR 
LOOP: JSR 
REQ 

JSR 

BCs 

LDA 

JSR 

CLEé 

RTS 

ENO_oF_STAB: SEC 
$34 C¢ RTS 


pa i 
oT 8 OS PN SS 


Cc 


(sTAB_PTR), Y 
STAB. BYTE 


HID 
(STAB_PTR), Y 
INCR_STAB_PTR 


RESET_STAB_PTR 
PEEK STAB 
ENO.OF_ STAB 
MATCH. SYMBAL 
Loop 

#$G2 

Avd_FA- STAB_PTR 


& 


$34D 
S34F 


MATCH _SYMBAL: 


5 


A 
TOP ASW WNMOHcowo cP 


$33 


Tou WD -oO- 


Cc 


LOOP: 


CHECK_END: 


MISMATCH: 


MATCH: 


SKIP_ENTRY: 


LDX 
JSR 

AND 

BNE 
LDA 
CMP 
BNE 
JSR 
INX 

MP 
LDA 

CMP 
BEQ 
CMP 
BEQ 
ISR 
AND 
BNE 

JSR 
JMP 
STX 
CLE 

RTS 
JSR 
JSR 
STA 

INC 

ISR 
SEC 
RTS 


LINE.OFF 
PEEK_STAB 


#$ 8D 


CHECK _END 
STAB. BYTE 
LINE, x 
MISMATCH 


INCR _STAB_ PTR 


LOOP 

LINE, Xx 
$29 
MATCH 
#$3D 
MATCH 
PEEK_STAB 
#$3¢ 


SKIPLENTRY 
INCR_STAB_PTR 


MISMATCH 
LINE_OoFF 


INCR_STAB_PTR 


PEEK_STAB 


STAB _DELTA 
STAB_ DELTA 
ADD. TO_STAB_PTR 


83SF 
q| 
‘ 


PEEK_LINE: 


$395 RESET_LINE: 


q 


S39A 


SKIP_SPACE: 


CR: 


SPACE: 


READ. ARG : 


LDY LINE_oFF 
LpA LINE, Y 


RTS 


LDA #$9¢ 
STA LINE oFF 


RTS 


ISR 
CMP 
BE 
CmP 
BE 
EL 
RTS 
SEC 
RTS 
INC 
oMP 


JSR 
STA 
JSR 
STA 
RTS 


PEEK_LINE 
#$OD 

CR 

#929 
SPACE 


LINE. OFF 
SKIP_SPACE 


READ_ BYTE 
ARG_HI 
READ_BYTE 
ARG_Lo 


O¢ 
FE 


RES 


co 


RESET_EMIT: 


EMIT_BYTE:: 


EMIT. CALL: 


EMIT_Ip: 


EMIT_REPEAT: 


LDA 
STA 
RTS 


LDY 
STA 
INC 
RTS 


LDA 
JSR 
LDA 
JSR 
LDA 
J MP 


LDA 
JSR 
LDA 
JSR 
LDA 
JP 


LDA 
TSR 
LDA 
JSR 
LDA 
JMP 


#309 
EMIT_ore 


EMIT_OFF 
EMIT BUF, Y 
EMIT_oFE 


$$ 2¢ 
EMIT_ BYTE 
STAB_PTR_Lo 
EMIT_8YTE 
STAB _ PTR_HI 
EMIT_LBYTE 


#$EA 
EMIT_BYTE 
#$FO 
EMIT_BYTE 
#393 
EMIT_BYTE 


#$B0 
EMIT_BYTE 
#$EB 
EMIT BYTE 
+$EBR 
EMIT_BYTE 


83E3 EMIT CONST: 


EMIT. LOAD: 
EMIT. ARG: 


EMUT_SToRE: 


WRITE. PROMPT: 


LDA 
JSR 
LDA 
JSR 
LDA 
IMP 


LDA 
JSR 
LDA 
JSR 
LDA 
JMP 


LDA 
IMP 


JSR 
LDA 
JSR 
LDA 
ISR 
IMP 


#$A4 
EMIT_RYTE 
ARG_LO 
EMIT_BYTE 
H$EA 
EMIT_BYTE 


#$ AD 
EMIT.8YTE 
ARG. LO 
EMIT_@YTE 
ARG. HI 
EMIT_BYTE 


#$8D 
EMIT_ARG 


RESET_LINE 
#°0 
WRITE_CHAR 
#°K 
WRITE ~ CHAR 
OUTPUTLN.TTY 


33 


83 


83 


$3 


S426 “TOPLEVEL: JSR WRITE_PROMPT 
q JSR INPUT_TTY 
ral JSR RESET_LINE 

JSR PEEK-LINE 
CMP #. 
BNE NEXT 
RTS 

NEXT: cmp #°C 
BNE NEXT 
INC LINE_OFF 
JSR  SYMBALIZE 
IMP ‘TOPLEVEL 

NEXT: CMP #7] 

BNE NEXT 

INC LINELOFF 

JSR DEFINE_SYMBAL 
JMP TOPLEVEL 

NEXT: CMp #°/ 

BNE NEXT 

INC LINE-OFF 

JSR REPLACE_REFS 

OMP 8 «TOPLEVEL 
NEXT: JSR SYMBALIZE 

JSR EMIT BUF 

IMP = “TOPLEVEL 


Zs nw 
St awn woe eget Hk OM 


1) 


— Tt GS soc tA moo 


46 


SYGY 
8467 
A 
C 


- owl 
oo ping ee ee SS Se ee Oe 


ee 
rconmownW A 


SHAT 


SYMBALIZE: 
Loop: 


NOT_EOL: 


NEXT: 


NEXT: 


NEXT: 


ISR 
ISR 
Bec 
MP 
JSR 
CMP 
BNE 
INC 
JSR 
IMP 
CMP 
BNE 
INC 
JSR 
MP 
CMP 
BNE 
INC 
JSR 
STA 
JSR 
J MP 
CMP 
BNE 
INC 
JSR 
JSR 
MP 


RESET EMIT 
SKIP_SPACE 
NOT_EOL 
EOL 

PEEK LINE 
+? 

NEXT 
LINE_ OFF 


NEXT 

LINE OFF 
EMIT REPEAT 
LOoP 

> 

NEXT 

LINE_ OFF 
READ_BYTE 
ARG_LO 
EMIT_CONST 
LooP 

tk°< 

NEXT 
LINE_OFF 
READ. ARG 
EMIT_LoAD 
Loop 


83 
33 


34 
83 


ie) 
84 


$3 
$4 


8| 


83 
84 


$3 
8Y 
8Y 


SHAR NEXT: 
C 
E 
BO 
3 
G 
q NEXT: 
Cc 
E 
C\ 
4 ERROR: 
$407 Fol 
q 


S400 REPORT_ERRoR: 
S 
F 
Da 


CMP 
BNE 
INC 

JSR 
JSR 
oMP 
JSR 
BCS 
JSR 
ome 
JSR 
LDA 

JMP 


LDA 
PHA 
JSR 
LDA 
JSR 
PLA 
JSR 
JMP 


#> 

NEX'T 

LINE OFF 

READ. ARG 
EMIT. STORE 
Loop 
LOOKUP_SYMBAL 
ERROR 

EMIT. CALL 
Loop 
REPORT_ERROR 
#$ 6g 
EMIT_BYTE 


LINE_oFF 
RESET_LINE 
#°? 

WRITE_ CHAR 


WRITE_ BYTE 
OUTPUTLN_ TTY 


33 


33 


31 


81 
$l 


BYHDE 
El 


All written and hand-assembled! 


DEFINE .SYMBAL: 


NOT FOUND: 


LOOP: 


SCANNED: 


COPY _ Loop: 


TSR 
Bcs 
JmMe 
LDA 
STA 
JSR 
CMP 
BEQ 
CMP 
BEQ 
JSR 
INC 
INC 
SMP 
LDA 
ORA 
JSR 
LDA 
JSR 
LDX 
LDA 
JSR 
INX 
CPX 
BNE 
LDA 
JSR 
IMP 


LookuP_SYMBAL 
NOT. FOUND 
REPORT_ ERROR 
#300 
TEMPLLENGTH 
PEEK LINE 
#$0D 
SCANNED 
#$29 
SCANNED 
WRITE_STAB 
LINE_OFF 
TEMP_LENGTH 
Loop 
TEMP_ LENGTH 
#$ 39 
WRITE. STAG 
EMIT_OFF 
WRITE-STAB 
#$ OO 
EMITBUF, X 
WRITE. STAB 


EMIT _oFF 
CoPY. Loor 
#L OD 
WRITE STAB 


RESET. STAB_PTR 


06 


83 


34 


$3 


83 


Cl 
83 


83 
83 


At this point it’s handy to have a list of the entry points, so | wrote that 
up too: 


ENTRY POINTS wn SITU-SOL 


RESET_STAB_PTR $930¢ 
INCR_STAB_PTR 3309 ADD_A.STAB_PTR 
ADD_TO_STAB_PTR 34D <— 3348 
SUB_STAB_PTR 8318 

PEEK STAB $329 
WRITE _STAB 833¢ 
LOOKUP_SYMBAL $337 

MATCH _ SYMBAL 8 34D 
PEEK_LINE S38F 

RESET _LINE 8345 

SKIPLSPACE 839A 

READ_ ARG 83AE 
RESET_EMIT 8389 

EMIT_BYTE 838E 

EMIT. CALL CSCC 

EMIT_ \F 83D5 

EMIT _ REPEAT S3E4 

EMIT _ CONST $3F3 

EMIT _LOAD S4d2 

EMIT ARG $4o4 


EMIT_ STORE S41 


WRITE PROMPT $ 9416 


TOPLEVEL B4AG 
SYMBALIZE 8464 
REPORT_ERROR S4CC 
DEFINE_SYMBAL S4DE 
TEMP. LENGTH SED (TMP_A in SITEMON) 
STAB_PTR[_LO] SGA 
STAB_PTR—-HI OB 
STAB _ DELTA Gc 
STAB — BYTE OD 
ARG_LO OE 
ARG_ HI OF 
EMIT_OFF 1d 
EMITBUF $ CI O¢ 
STAB_ BASE $ $909 


Now, to enter it... luckily, entering hex digits with SITU-MON is a lot 
easier than entering bits using front-panel switches. 


i rn 


") VICE: C64 emulator 


BSSGARASSESSSGEBEE 


we 
ies) 
wi 
io) 
” 


VSBAGSECSSSEARASSEBESSESSSEBES 
SSBRESSCSSEARASSEBESSSBSSEBES 
6BisASSEDEGB 

69i168A4ACES83 

ll —————— 
6 


68D83i18663866 
4D 


8 
3 
8 
3 
6 
3 
8 
8 
i 
8 
2 
6 
3 
8 
3 
8 


QVNOoOoorPVDPVTOuUoO0o 


66 
As 
83 
WA 
83 
WA 
83 
Hi 
83 
W3 
83 
WA 
83 
WA 
83 
H2 
83 
H2 
83 
a 


VICE: C64 emulator 


69i16AACESS3 

6S3262983F BOC264D8S3E6F GAS62 
68DS3i18663866 
E2629832986D66EASEDDDEGCEDGi12266983 
C4F SSBDGS6CECS26F 61 i1CS6DF 6eD 
S83298ED6GAR269834CEF S386FEiIS66 
S83262983856CE6SC26ED833866 
EBS66C666 

SSSFEGSG 

FSSCS6DF 6E6CS26F 6641 S6ESS66E6GFE4C9AS 


Bwaow 
OnNog 


ta 


DSisSeF 26408i1856E66 


ROD BOOVSVOVO70N% 
CALM BDSOUNNOSV "LON" 


83 
WA 
83 
H2 
83 
H2 
83 
WA 
83 
HE 
83 
H2 
83 
H2 
83 
WA 
83 
WA 
83 
H2 
3 

83 
H2 
83 
i 


__, > 


") VICE: C64 emulator 


FSSCS6DF 666CS26F 6641 S6E63S66E6GFE4CSAS 


DSisSeF 264D8i1856E66 

6851666 

639966CiE6i666 
SB26BES3SASGA2ZEBESSASGBACBESS 
AZBBESSASF G2GBESSASES4CBESS 
S26BES3ASF AZGBESSASERACBESS 
S26BESSASGE2ZSBESSASERACBESS 
D2Z6BESSASSE2ZSBESSASGF ACBESS 


o 
a 
“ 
fe) 
& 
te 


IS3AS4F 266BS8i1AS4B266B8i14C8S281i 


833A 
aces 
S3AE 
H264 
83B3 
WASS 
S3BE 
WAdi 
83C6& 
WAS2 
83D5 
WASE 
S3E4 
WASD 
83F3 
WASA 
8462 
HASA 
S4ii 
HWASS 
84i6 
H2693 
8426 
i 


__, > 


") VICE: C64 emulator 


D26BESSASSE2ZSBESSASGF ACBESS 


o 
a 
“ 
for) 
rs 
te 


IS3AS4F 266BS8i1AS4B266B8i14C8281i 
6842695981269583268F S3CS2ED660i166 
BDGSGSEGFE2664844C2684 
DDGSSEGFE2SDES44C2684 
FDOGSEGFE2636844C2684 
4842666Ci4C2684 
S83269AhS396634CC7S4268F SSCS3FDeEG8 
E26059834C6 784CS2i1D668E6F E26E 483 
TS84CS23DGGDEGF E264D081856E26F 383 
TS4CSSCDGSEBEGFE E2GARES3S26802844CE 784 


AWN MLO Co D> 


Ss 
i 
be 
i 
8 
2 
8 
3 
be 
4 
— 
4F 
3 
> 
8 
6 
6 
7 
6 
8 
Cc 
Ss 
Cc 
fi 


PMOMNNMD AMON 


WA 
84 
WA 
84 
H2 
84 
H2 
84 
WC 
84 
WC 
84 
WC 
84 
H2 
84 
H2 
84 
WE 
84 
w+ 
84 
H+ 
84 
i 


_ 


") VICE: C64 emulator 


S83269AhS396634CC7S4268F SSCS3FDeE8 
E26D5834C6784CS2i1D66S8E6F E26E 483 
TS4CS23SDG8DEGF E264D081856E26F 383 
TS4CS3SCVGGEBEGFE E2GAES32602844CE6 784 
EDGGBEGF E26RES32611844C6 784 
TSSBBG626CES34C678426CCS84AS664CBES3 
E48269583A93F 266B8i168265C8i4C828i 
TSSBEG3S4CCCS4A96685F D 

FS3SCS6DF 6GECS26F 866A 

SSSEGFEEGFE D4CEARS4ASF D 
B6263683A516263683A266BDE6Ci 
SBS3SESE 41 6D6F 5ASGG2636834CE683 


H26B8 
8476 
HE GE 
8487 
H4C6 
8438 
H4C6 
S4AA 
WC S33 
84B93 
H263 
84CC 
HWASE 
S4DE 
H263 
S4EA 
H2638 
S4F5 
H263 
856i 
Wess 
$5186 
H263 
8526 
i 


All done! 
Of course, | made several errors. 


| caught one error while reviewing what | had entered with the M 
command. | had simply mistyped a line. That one was easy to fix. 


Other errors - | had to test the program first. 


And in order to test it, | needed to have a symbal table for it to work 
on. | made one up with two very simple “commands” whose effect 
would be both obvious to see, and non-intrusive on the rest of the 
system. | decided to have them call two of the simpler routines 
present in SITU-MON (WRITE_PROMPT and INCR_ADDR). (And 
yes, you’re right, they should really be called $ADDR and $INC, with 
the dollar signs — thank you for paying attention to the spec. But, this 


was just to test...) 


DEMO SYMBAL TABLE 


$ 9I0¢d “ADDR” #$84 #$04 4144 44 52 84 gy 


JSR WRITE_PROMPT 26 74 $I 
q RTS 64 
$09 GA “INC” #$83 #$¢4 47 4E 43 $3 OY 
F JSR INCR-ADDR WW dC 3} 
La RTS CO 
3 #$ G6 wt) 


TEST DRIVER 


SIGO JSR INPUT_LTTY ag 4S 8! 
JSR S¥M RESET_LINE 2G 4S 83 
TSR SYMBALIZE 2g CY $Y 


RTS O¢ 


VICE: C64 emulator 


ECS26F BGAZESESSEGEEEGFE D4ACERS4 
DESSS263E683A51G263E683A266BD06 
BSES3ESE 41 6D6F 5AS862636834CE6 


6 


4445 2846426748166 
E43836426DC8i6666 


8 
F 
c 
F 
2 
= 
8 
: 
2 
6 
8 
8 
4 
A 
4 
4 
SF 
: 


8 
F 
- 
8 
i 
i 
3 
2 
4 
2 
S 
6 
i 
8 
Ss 
i 
3 
8 
4 
Ss 


M 

ME 
84 
M 

MA 
85 
M 

Mc 
85 
M 

ms 
85 
As 
84 
AS 
63 
w+ 
63 
Wa 
63 
As 
83 
WA 
83 
a 


| wrote the test driver so that | could A8200 then G in SITU-MON, 
enter a few symbals, and then, after it returned to SITU-MON, AC100 
then M to look at the code it generated. 


One obvious symptom during testing was that SKIP_SPACE didn't 
seem to do anything at all. It turned out that | had completely mis- 
assembled LDY LINE_OFF. (You can see this fix, and all the other 
fixes, in the listing above, if you look for them.) 


Another one was that the addresses in the generated code weren't 
right. It was emitting JSR’s to the size-part of the symbal table 
record, not the compiled code. It turned out that 

in LOOKUP_SYMBAL | had forgotten that ADD_TO_STAB_PTR gets 
its input from the memory location STAB_DELTA, and not from the 
accumulator. Luckily the fix was easy: add a new entry point called 


ADD_A STAB PTR just before ADD TO STAB PTR, and call that 


one instead. 


Once | fixed that, | was able to compile simple “programs”: 


©@® VICE: C64 emulator 


INC INC ADDR 


INC INC ADDR 


84 
OK 
InN 
OK 
AD 
84 
OK 
InN 
84 
OK 
CI 
OK 
JTHREE 
OK 
TH 
84 
OK 
TH 
84 
OK 
TH 
84 
84 
OK 
' 


There was still one more bug. The code generated when compiling a 
! (repeat) was wrong — it was jumping one byte too far back in 
memory. Once spotted, that was another easy fix. And then... 


VICE: C64 emulator 


7 @ 
bad 9 Lae 
Mug 


cod 


al 
ut 
ax 
ray 
ra) 
< 


© 
coro a) “ih | “ 
Wty Cw «a AN ZN 

CHOOT MDa wl Tad tnd add Tae 
OCOWOTOMMOUOCMOCHOUCROE 


¥ VICE: C64 emulator —- + 


N 


J 
0 
A 
8 
8 
8 
8 
8 
8 
8 
8 
8 
8 
s 
8 
8 
$ 
8 
8 
8 
s 
8 
8 
8 
8 


Debt ebabetatabetetebabatetatatatatatetctattbet 
WWWWWWWWWWWWWNNNNNNNNN 
OWDOSNMVNLWNESIMOIOBDOON = 


Huzzah! 


A moderate success. We have, on this emulated computer, a 
programming environment, hand-written and hand-assembled and 
hand-entered in hexadecimal (using a less sophisticated 
programming environment, which was itself hand-written and hand- 
assembled and hand-entered in binary using simulated front-panel 
switches. ) 


But why do | consider this a moderate success rather than an 
unqualified success? Well, I'll write a retrospective blog post on that 
topic shortly; stay tuned! :) 


1 note 


| love bits. Bits are great when you're 
coding and you want 2,000 of something 


(with apologies to Mitch Hedberg for the title of this post) 


Right! So almost as soon as | finished writing the code for SITU-MON 
| started entering it into the emulated Commodore 64, using the 
simulated front-panel switches. At first this was in dribs and drabs, a 


few bytes here, a few bytes there. 


¥ VICE: C64 emulator —- 


| won't bore you with thousands of screenshots; it all looked basically 
as described in a better front-panel simulator. (And for what it would 
look like in the physical world, watch the video on the loading the 
code post.) It’s not difficult, exactly, it’s just tedious and fatiguing. 


Finally, | had entered all 2,000 bits, and | reset the address to the 
beginning, planning to review the bits | had entered to confirm they 
were the same bits that were written on the paper. 


To my considerable surprise, they were completely and utterly 
different bits than on the paper. They were nothing like what | 
entered. 


Then | realized what had happened. The SITU-MON code starts at 
$8100, but this is inside BASIC’s default memory range, which 
extends up to $9FFF. Also, the improved front-panel simulator 
creates a lot of temporary strings compared to the first version. 
These grew downward in memory and completely clobbered the 250 
bytes | had entered! 


TO READ A MEMORY MAP 


img fip.com 


So | lowered the top of BASIC memory, and started all over again. 


VICE: C64 emulator 


seeet COMMODORE 64 BASIC U2 test 
RAM SYSTEM 3839ii BASIC BYTES FREE 


* 


vO UA 
-- NMD AD Sb 
"Io ome me 


RONTPANEL™ ,8 


Bran FOR FRONTPANEL 


E 
— 
i 
Ef 
re 
EA 
0 
E 
U 


Aarw rw 
zD>D>D 
acon 


The second time doing this, at least, | was able to enter the bits much 
more quickly; | had had practice, and had a block of time to myself 
that | could dedicate to it. And when | reset the address to review the 
code, it was, in fact, the code | entered. 


Well, mostly. | skipped a byte about 80% through. So, | re-entered 
the last 20% and reviewed it again. In the second review, | found 
one wrong byte, but thankfully it was all in sequence and | didn’t have 
to shift anything. 


Satisfied that what was in the computer matched what was written 
down on paper, | reset the address to the beginning again and... 
executed! 


And nothing happened. It just hung. 


Thus, the debugging began. 


| pressed RUN/STOP+RESTORE and re-RUN the front-panel 
simulator — the moral equivalent of pressing a Reset button ona 
single-board computer which resets the CPU to a known state 
without affecting the contents of memory. 


But how to debug something like this? 


| looked back to the listing on paper and traced the execution path 
through it, as best | could, by hand. | couldn’t see where there was a 
problem. 


The first routine the code calls is WRITE_PROMPT. In the front-panel 
simulator, | advanced to the WRITE _PROMPT routine and executed 
it. And | got this: 


v VICE: C64 emulator —- + 


iddddtidtitititdtitdtiititt’$ititintidtidtidddtiddtiditinitintdcas 
aaddtidtittitvititit*#ttidtit#tittidtitdtiditiddtiditinctintdaicid 
aadtdttiddtittdtit#itititdtidititQi®ddidditidtinitintntnntna 
ataddtiti§itititt**«’_aiddtditititidtdtdtidtidtitidddtiditidtinitidnadd 
aiddddtidtititidtit*tiitttthtthttntttitttitntit*tintitithnt} ttiititl 
fadtdttidtittit*ttttitttit*ttititittitidtititidtidtdtititiddtidditidididididd 
aiadidddtidtiittittit@tidttddt$tdtidti$ititidtittitdtiddtiddtidnitincaa 
tadtdttidtitttt*titttt*tt***t****’*’i«**=’itntidd\’'’d’kidttittitititittthd 
aiaidtddtidtititittiti*itittttitt*ttt*ntdntdddddddnnnna 
fadtdtttti§@tittit*ttititidtittit#ti#ttidtitdtitditidtiddtidditiddtidddtiditidd 
aidaidddtidtitititittti#titittt*tit#ti#t#tititi#dtitditi$dtiddtidditiddtidiciaisit 
aaidtdtittditittit*iit*d’dtddtdidtddtdttidtititiddtitdditiddtiddtiddtiddtiddl 
aiaidtidtitttititittt*@tintdtddtdtdtiddti$ttitiddtitttittdtititititiddtiddtiddid 
fadtdtttitd§tittiti@ttittittittitttittitWtititititititddddddddddd 
iaidtdtitt*tittittti@tittit*titdtdtdtdtittitdtittiti$tdtitttidditiddtidditidiaidt 
taididttiti§tttitttf#dititt*ititti*tititit*ttiddtdtdtttiddtitttiditidietiad 
taitdtidtittittit#ttit*tit§tittttt§tit*ti#t§tititdddddddddasd 
faidtdttitd§tittit*tittittittittittitttititititdddddddddddadd 
taitidtittt*tt’ttd’ddddddtdtdtiddtdtdtidtittdtitititddtittitiditiditididid 
ftadtdtttid§tittid#tit*ti#titidttititidtidtititit@tit*titttittiititittttdtd 
iaitidtittittittt*tt*tttt*titht*tG@ttitttthtttthtttt k?htddad 
faidtdttiti§ttittt#ittttittittittittitd#ititi tidttititiddddddddda 
aiaidtdttttddtditddtddiddddiddiddidddsdddsiaddadsd aad 
taidttitdi#titttit*ittittitititttttittitititfititiitittitiddtittittititiddd 


Yeah, no, that definitely wasn't in the spec. 


A mild panic set in. The bug could be anywhere. | might've written 

down the wrong binary for a hex value; | might've written down the 
wrong hex value for an opcode, or | might’ve made a programming 
error in the code itself. 


| had just finished entering 2,000 bits on a simulated front-panel — for 
the second time! — and | was in no mood to spend the rest of the 
weekend, or possibly the rest of the RetroChallenge, poring over my 
program. 


So | took a bit of a mulligan. It was a small thing, and | could 
rationalize it by saying “let’s pretend there are 16 green LEDs on the 
front panel for the address lines” or something. But still, I'm not 
proud of it, and it should count against my RetroChallenge score 
(however vague and nebulous a concept that may be.) 


| converted the address of the OUTPUTLN_TTY routine to decimal 
(33153), dropped to BASIC, and PEEK’ed that address to see what 
byte was there. The first instruction of OUTPUTLN_TTY is LDA 
#$00, so | was expecting to see 169 ($A9), but... 


i VICE: C64 emulator —-= 


Noticing that the byte just before OUTPUTLN_TTY was $87, it 
occurred to me: maybe | made a mistake assigning addresses to 
labels. 


So | read over the code again, and, indeed. 


$139 RD.HX. JSR $SI3G | Ad 3¢ BI 
$13BR PS.HX. LOY #$¢¢ Ad $¢ 


See the problem? 


So! A bit painful that this mis-numbering happened so early in the 
code, but, there was nothing to be done except to go through it all 
and correct the addresses: 


$8lgo 
8193 
9106 
$193 
SIDA 
8I¢D 
BID 
8113 
Sus 
8117 
SIA 
Suc 
SIE 
Slal 
$123 
8125 
Slag 
SI2A 
Ziac 
Siar 
$13¢ 
Likes 
$135 
BIZ 
$138 
$139 
$i3c B38 
ViZE sp 


Simi StH 


MAIN 


prise 


RD. HX, 
PS. HX. 


S143 $ Bi 
T44 $143 
S $44 
G GINS 
3 8I47 
A BHd 
c 848 
314 D Si4c — RO.BY. 
TISB Si4e 
{ 


BiSC BSS weer. 
D siSCc 
E ISD 
F @ISE 
31GB ise 
1 %ie¢g 
4 BiC3 
2IGS Step We Hx, 
7 BGG 
% F167 
FIGB Sted WR cH. 
dD Bec 
Bi7g FICE 
| sI7¢ 
3 87a 


RD. cH. 


IsR $tlagw}] ag 14 8! 
ISR $8igzas!| Aad 495 FI 
LDA #$¢1 Aq ol 
STA $FE | gS FE 
IsR $81g | 2 IG 31 
Jue $3ige | 4c GY # 
LDA $Cggg ss ADs FG 
CMP #$4] cov 4 
BNE $63 Deg ¢ 
IMP $BIAT Ag 4c AB BI 
CMP #$4D c4 40 
BNE $¢3 De 3 
IMP $FIBXG3 ue BB EI 
cme #957 cq $7 
BNE $93 De 63 
TMP $8icHcs 4C Cg BI 
CMP #$47 cq 47 
BNE $43 | De 93 
Jue ($90F8) cc FB og 
RTS oe 

LoY $Fe | AY FE 
Loa $cog¢,¥ BY $F Co 
INY cy 

STY $FE 94 FE 
RTS o¢ 

ISR $8139 | ag 3¢ BI 
LOY #368 = AG og 
CHP $8lER,Y) DI ER 8 
BNE $¢a | Dd ga 
TYA % 

RTS Gs 

INY ce 

cry #$1¢ cg I¢ 
BNE $FH Do FH 
LDA #$9¢ Aa 9 
RTS 6g 

Tsk $9139 ag 39 Bi 
Asi A A 

ASL A A 

ASL A GA 

ASL A A 

STA $FD $5 FD 
ISR $8139 | 2B 39 BI 
ORA $FD oS FD 
RTS Gg 

PHA 43 

LsR A 4A 

LSR A 4A 

LSRA 4A 

LSR A 4A 

TSR $6lG4Cs| as oH 31 
PLA G3 

AND #$9F a4. «OF 
TAY AS 

LoA $81EQ,Y| 89 EA $1 
LOY $FE AY FE 
STA $<6d,y] 99 OG c¢ 
INyY C3 

STY SFE $4 FE 
RTS 6g 
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Colocece Goll lool {oocccoot | 

Dooce clei Leacrel 
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POCCCOT CILOCIoIO 
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lloo tooo 
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O1LO C000 . 


PITH $ GHZ 
BTS 
$77 
1719 
sic 
SITE 
SH 
4Y $133 
SHG 
1 ise 
Cc BsB 
F RISE 
SIF 
B41 
BAZ 
Hat 
7 giae 
A &I99 
Dd 
E 


nv > an 


Brac 
S\9D 
SI9F 
SlAl 
S lay 
SAT 
B IAA 
SIAC 
QIAF 
2 iBi 
BR 
S $184 


= 
is 
wa 


$ID 


Sd 3 
ta 9 


>Sajnw-— 
2 
m 
Cc 


= 
m 


wr.pe. LDA #$0¢ AQ og 
STA SFE $5 FE 
LoA $FC AS Fe 
TSR $888 Se | 26 SE BI 
LDA $F8 AS FB 
JSR $3ISBSC | 2D SB BI 
ofin = LDA 4$6D AQ oD 
TSR $BicAce | ag cw BI 
ORMY LOY #$9¢ Ag 6¢ 
LDA $c#¢¢,Y | BF GO co 
TSR $ FFA a¢ Da FF 
INY cs 
Cup #4¢D <q 9D 
BNE $F5 be FS 
RTS ce 
wey LDY a4¢¢ Ag O¢ 
TSR $FFCF ag cr FF 
STA $c6¢¢,¥ | 99 OG c# 
INY cg 
CMP #$¢D cq oD 
BNE $F5S pg «FS 
STA $cH9¢,Y | 99 Oo cg 
TMP $FFpr 4c Da FF 
strap. JSR Game yo] Ag 4O BI 
STA $FC $5 Fe 
IsR $eiwe4O |) As Yo BI 
STA $FB 85 FB 
RTS G¢ 
Ro. Men LOX #419 Ar 16 
LoY #$¢¢ Ad o¢ 
LOA (#7B),Y | Bt FB 
J5R $sisesc | 36 SB SI 
TSR $fiPBoOc | 2d YB Bl 
DEX CA 
BNE $F3 Dy FR 
yer $siers2 | 4c BK 8! 
wh.nem LOY SFE AY FE 
Lod $ede¢,y¥ BI $6 c¢g 
CMP #$¢D c4a @D 
BNE $91 DS gi 
RTS cg 
TsR $BINC4O | ag 4O $I 
Loy #$¢¢ Ag o¢ 
STA ($F8), Y a F6 
JSR $BIDBDc | ag DB Fl 
gmp $8icHcs | He CH Bl 
weR CLE 19 
LDA $FB AS FB 
Ape #$¢1 cl OI 
STA $FB 85 FB 
LOA $Fc AS Fe 
Ade a¢eg cl og 
STA $Fc $5 Fe 
on RTS | 6¢ 
if | 3 
$32 32 
$33 33 
34 —3y 
1 35 
36 
44 | 37 
$33 38 


lolo lool 
loco diol 
lo1oolol 
oo(o00c0 
lolooict 
OO|o o°00 
lo1o lee! 
0010 o000 
{Ole o6c0 
1ortioot 
oo1cocc0e 
llootooo 
Hloo1wos 
[lof oooo 
O110 0000 
1016 0000 
o0190 9 ECO 
1oorlt oo, 
1100 1000 
11 Celool 
{1010000 
foot lool 
o100 1100 
0010 0000 
l[oooolel 
Goto 9000 
locooio| 
o1ld60000 
[ola Colo 
1010 C000 


lotloool 
COlo0000 
©0110 0000 
11601010 
1L Ol C000 
Olooltos 
lolo O100 
loll tool 
lLootool 
[tol coco 
©1110 0000 
OO10 Cfoeo 
1oOleo coco 
lool Soe; 
0010 0000 
Sloe lions 
Oool todo 
lo1tootol 
O10 lool 
1000 Oo} 
LOlo Clot 


Ollo lool 
looocoiol 


Oll10 %000 


ooll 
ool 
oot 
Ccll 
oo 
ool 


e000 
ooo 


oolt 


Ole} 
COll otto 
oon ont 
Oo tooo 


oolo - 


oO1c°e 


bed] -Tehel 2-10) 
Lethe thro 
Litt Moo 
olol 1o0b 
ryt Lott 
OLol lone 
coooltlol 
CLIO Lolo 
Oocecocea 
eo0o006000 
11OLloold 


Oooo I1Ol 
LLttotor 


Qoeoocoes 
poorer 
00000000 


ooootlol 
(tL Lotol 
Ooced0000 
(loloarod 
oloollog 
rliLtloo 
0100 [Lod 
Ptrilorl 


Oo0e| oe00 
oQo000ceO 


(tition 
Clol loop 
1101 109b 


thet oor 
1006 coép 
ltttitto 
Co0CC C000 
oooollol 
Cococooo!l 


O10 1109 
CO 000080 
Lerttors 
tol teob 
Loo olod 


tLrttotl 
Occecoo!| 
ttitoul 
(ttitioo 
00000000 
tlititeo 


a se cseiceeee ne 


JO00 Cco|[ 


loee ocol 


1900 cco| 


110000900 
yererny 


eee 
{19000000 


tlooefoo - 
Hertel 
looocoel * 


10a0 Cool - 


1 000 0001 
100 0000] 


loco cool 


\locoeeo 


. 
1oo0eoo( . 


loco CGO} « 
\oooooo! 


CClliool . 
Olcocoo[ . 
Glooocl1o 
ooo OOll 
O1Cooloo 
olooolol 


OOCollo 


And then, back to the front-panel simulator. Reset the address to the 


beginning. Keep advancing the address until you get to the next byte 
that needs correcting, enter the new byte, repeat. A little nerve- 
wracking, but not terribly difficult, because | was getting pretty used 


to this by now... 


Then, reset the address to the beginning again, and... execute! 


v VICE: C64 emulator = + 


Hey! That looks... like what | expected! Let’s see if it works: 


¥ VICE: C64 emulator —- + 


ODS 
bm COD 
® 


Sere O-OOOrrO OO 
Secor GOu0roeooce4 ooo 


48126958i1AS68i185F E2616814Ce68i 


b= ae 
@ 


2345678S9ABCDEFF 


be ae 
® 


M 
M2 
8 
A 
Cc 
We 
Cc 
A 
Cc 
M 
M6 


23456789ABCDEF F 666666666 66666 


be ae 
® 


Boaosao 
ws 
® 


It works! It works! 


This is a very nice feeling — one that makes up for the earlier 
disappointments. 


So now... we have a machine-code monitor! It’s crude and ugly, but 
it does the trick, and it’s small — 250 bytes, or maybe 251 bytes now, 
because of the addressing correction? I’m not sure, but it’s still less 
than 255 bytes, and that’s great. 


ENTRY POINTS (N StTU-MON (congEectED) 


MAIN $81 DD 
DISPATCH $311¢ 
READ. CHAR $313¢ 
READ_ HEX $ 3139 
PARSE _HEX S Tze 
READ_ BYTE $314D 
WRITE. BYTE $3ise 
WRITE_ HEX $3165 
WRITE. CHAR $316R 
WRITE _ PROMPT $3174 
OUTPUTLN_TTY $3192 
OVTPUT_ TTY 33) 37 
INPUT TTY $8195 
SET-ADDR $31A8 
READ_MEM $3183 
WRITE_MEM $8165 
INCR. ADDR $3IDC 
HEXDIG (TS $31 EA (not callable) 
LINE $ COED 
ADDR (—Lo) $ FB 
Avo®— HI S Ft 
he oa : _— (only used x READ_ BYTE) 


We’re not done, though! A machine-language monitor is a kind of a 
programming environment, but it’s not a very good one. We won't 
have to convert anything to binary, and entering lines on a keyboard 


is a lot easier than using front-panel switches. But we do still need to 
hand-assemble our code to hex, and compute addresses and so 


forth, which means we'll still be using paper a lot. 


Here’s an example of how much easier it will be, though. Its a 
fancier version of the warm-up exercise, the “echo” program. It 
displays a sort of prompt between lines, and lets you quit by starting 


the line with a period. 


$82adg¢  EcHoa: LOA + AY o¢ 
2- STA LINE _ofe 8S FE 
4 LDA #°>? AY 3E 
6 JSR WRITE_cHAR 20 68 BI 
q JSR OVTPUTLN_TTY Ww «FA QI 
er JSR INPUT_TTY ag 95 Bl 
F LDA LINE AD @¢% C¢ 
ai 2 CMP #°. Co «(QE 
YW BNE CONT DY gl 
G RIS Ge 
ERI 7 CONT : JSR OUTPUT _TTy 26 &% $1 
G21 A JmMP ECHO 4C GO FL 


Note that, since we don't have to convert to binary anymore, we can 
format the listing on paper more compactly. Entering and reviewing 
and running it is a matter of a few monitor commands: 


¥ VICE: C64 emulator —- 


S6SSF EASSEZSEBS126828126958i1ADesCcs 
EDe6i16626878i14C8882 


BSSF EASSEZSEBS126828126958iAD 


SCS2ED861662687814C888268060666 


SVN@ Oo BNKOrOSN® 
fan) 


Soom S09 Secrnreooo 
ia) 


66 
As 
82 
WA 
82 
WC 
82 
As 
82 
M 

MA 
82 
M 

M6 
82 
As 
82 
G 

> 

ft 


And we test it a bit to make sure that it works as designed... 


¥ VICE: C64 emulator = + 


r 
Sve 
eoonm 


S8CS2ED8681662687814C8688266860686 


Moon 


8 
A 
s 
G 
> 
H 
H 
> 
E 
E 
> 


Bo Ve4+VEEv 


I’m quite happy with this! 


Now, to design and write a better programming environment that we 
can enter into the computer using SITU-MON here... 


SITU-MON 


OK, LET’S DESIGN & write A SIMPLE 
PROGRAMMING ENVIRONMENT —— A 
MACHINE-LANGVAGE MONITOR. 


(A.K.A. DEBUGGER. NOT To BE CONFUSED 
WITH A VIDEO MONITOR, OF COURSE.) 


JT WitL LACK MANY FEATURES OF A 
“REAL” MONITOR, BUT IT WILL LET US: 


- ENTER BYTES IN HEXADECIMAL AND 
WRITE THEM )NTO MEMORY 


* INSPECT THE CONTENTS OF MEMORY 
AS HEXA DECIMAL 


» CALL MACHINE-LANGUAGE ROUTINES 


..AND IT WILL BE SMALL ENOUGH THAT 
PLL BE ABLE To ENTER IT, IN BINARY, 
USING ERONT-PANEL SWITCHES, WITHOUT 
GOING MAD. MAYBE. 


PARSE Apor 
FROM LINE 


READ I© BYTES 
FROM ADDR, 
WRITE To TTY 


READ BYTES 
From LING, 
WRITE to ADDR 


CALL RouTINE 
AT AoorR 


50, WE'LL NEED: 


~ A MAIN LOOP WITH CODE TO DISPATCH 
TO THE VARIOUS MONITOR COMMANDS 
(FOUNTAIN PEN) 


* ROUTINES To PARSE THE LINE THE USER 
ENTERED, FOR HEX DIG(TS Etc. CGREEN) 


* ROUTINES TO FORMAT OUTPUT FoR THE 
USER, AS HEX DIGITS ETC. (BLUE) 


* ROUTINES TO TAKE INPUT FROM, AND SEND 
OVTPUT To, THE VIRTUAL TELETYPE (PURPLE) 


» THE MONITOR COMMANDS “THEMSELVES (RED) 


» SOME MISCELLANEOUS UTILITY ROUTINES 
(FUSCHIA OR WHATEVER THIS 15) 


NOTE THAT THE CODE |S NOT COMMENTED (except 
tuhere T’ve made last-minute alterations) BUT EACH 
ROUTINE SHOULD BE SIMPLE ENOUGH To FoLLow 
FOR ANYONE WHO KNowS 6S@2 ASSEMBLER. 


MAIN. LOOP: 


DISPATCH: 


NEx T: 


NEX T: 


NEXT: 


NEXT: 


JSR 
JSR 

LDA 
STA 

JSR 
SMP 


LDA 
CMP 
BNE 
TMP 
CMP 
BNE 
TMP 
CMP 
BNE 
Imp 
CMP 
BNE 
MP 
RTS 


WRITE _ PROMPT 
INPUT_TTy 


#1 

LINE_ PTR A.K.A. LINE. OFF 
DISPATCH 

MAIN. Loop 


LINE 

#°A 

NEXT 
SET_ADDR 
#'M 

NEXT 
DUMP _ MEM A.K.A. READ. MEM 
+ W 

NEXT 
WRITE. MEM 
#7G 


READ_ CHAR: 


READ _HEx: 


PARSE _ HEX: 
Loop: 


NExT: 


READ- BYTE: 


LDY LINE_ OFF 
LDA LINE, Y 


INY 


STY LINE ofr 


RTS 


JSR 


READ_ CHAR 


Falithrough 


Lby 
CMP 
BNE 
TYA 
RTS 
[NY 
CPY 
BNE 
LDA 
RTS 


TSR 
ASL 
ASL 
ASL 
ASL 
STA 
ISR 
ORA 
RTS 


#499 
HEXDIGITS, Y 
NEXT 


#$19 


LooP 


#$ 92 


READ. HEX 
A 

A 

A 

A 
TEMP_LA 
READ HEX 
TEMP_A 


WRITE_ BYTE: PHA 
LSR A 
LSR A 
LSR A 
LSR A 
JSR WRITE HEX 
PLA 
Fall through 

WRITE_HEx: AND #¢ OF 
TAY 
LDA HEXDIGITS, ¥ 
Fallthrough 

WRITE ~ CHAR: LDY LINE_oFF 
STA LINE, Y 
INY 
STY LINE oFF 
RTS 


WRITE _ PROMPT: 


OUTPUTLN_TTY: 


CWITUT ..FTr 
Loop : 


INPUT_TTY: 
LooP: 


LDA #9¢¢ 

STA LINE_OFF 
LDA ADDR-HI 
JSR WRITE_BYTE 
LDA ADDR_LO 
JSR WRITE_BYTE 
Fallthrowgh 

LDA #¢¢D 

JSR WRITE _ CHAR 
fall through 

Loy #399 

LDA LINE, Y 

JSR CHRoUT 

INY 

CMP #¢¢p 

BNE Loop 

RTS 


LoY #$¢¢ 

JSR CHRIN 

STA LINE, ¥ 
INY 

CMP #$¢D 

BNE Loop 

FMP—CHROUF 

for safety 


STA LINE, Y < 
JMP CHROUT during WRITE_MEM 


( LINE_oFF 
LINE, Y 


NOW, DATA... 


LINE WILL BE THE SAME AS IN THE 
WARM-UP: $COOP 


THERE ARE ONLY 4 OTHER MEMORY LOCATIONS 
THAT ARE USED, AND WE CAN PUT THEM IN 
THE ZERO PAGE TO KEEP THE copE SMALL. 


ADDR HAS ITS Low BYTE AT $FB 
AND ITS HIGH BYTE AT $FC 


TMP.A IS STORED AT....... $FD 
LINE_OFF 1S STORED AT.... $FE 


WITH “THESE CHOICES, THE SIZE of THE 
CODE COMES To... 


A50 BYTES! 


THAT'S 2,000 BITS! 


THAT’S DOABLE... | THINK... 


$8I1Go 
813 
8166 
3163 
RIGA 
8I¢D 
BID 
8113 
SS 
BII7 
SIA 
SUC 
SIE 
S12) 
$123 
8125 
Blas 
SIBA 
Place 
Siar 
$13¢ 
BISA 
$135 
BI3G 
$138 
$1349 
$13B 
313D 
sI4¢g 


$34 
8143 
S144 
SYS 
BINT 
BNF 
sI48 
Slye 
SI4F 
$15¢ 
$151 
3159 
BSB 
Ziss 
BIS8 
BISA 
ZiSB 
gISC 
ZISD 
ZISE 
SIS FE 
S169 
BiG3 
BIGY 
BIGG 
B\GT 
S1GA 
BIGC 
SIGE 
B7¢ 
BRITA 


MAIN 


DIsP 


RD. cH. 


RD. HX. 
PS. HX. 


RO. BY. 


wR. BY. 


wR. HX, 


WR. CH. 


ISR $8173 
IsR $8194 
LDA #$¢) 
STA $FE 
TsR $sig 
yJmMeP $31Ge 
LDA $Cog¢g 
cmp #$4I 
BNE $43 
IMP $8I1A7 
CMP #$4D 
BNE $63 
IMP $FIBX 
cme #357 
BNE $63 | 
TMP $3Ic4 
CMP #$47 
BNE $43 
TMP ($¢¢r8) | 
RTS | 
LDY $FE 
Loa $cog¢,y¥ 
INY | 
STY $FE 
RTS 
ISR $3139 
LoY #$¢¢ 
CMe $81E7,Y 
BNE $¢x 


TYA 

RTS 

INY 

cey #$1¢ 
BNE $FH 
Loa #$2¢ 
RTS 

TSR $9139 
ASL A 
ASL A 
ASL A 
ASL A 
STA $FD 
TSR $9139 
ORA $FD 
RTS 

PHA 

LsR A 
LSR A 
LSR A 
LSR A 
ISR $81C4 
PLA 

AND #$¢F 
TAY 

LoA $81E9,Y 
LDY $FE 
STA $CO¢¢,y 
INY 

STY $FE 
RTS 


| 2¢ 


ad 13 81 
ag 94 81 
Aq GI 
gS FE 
1d 81 


4c Ge 8 
| AD go cd 


«84 FE 


cq HI 
Dg o 


| 4c AT 8 


c@ 40 


| DG 3 
| 4c BQ BI 


cq $7 
De g3 
HC CH BI 
cq 47 
De $3 
GC FB Og 
od 


oA FE 


BI $F Co 
cy 


og 
ag 3¢ $1 


| AG O¢ 


DY ET 8 
Dd $2 


FY 


02800000 
00( 00000 
1LOLOLCo, 
| ooo Clot 
0016 0006 
O1001!900 
1o1o 1101 
11001400! 
1101 0000 
Cloo1l08o 
1100 100] 
[lol °000 
01090 1100 
[190 Loo! 
[LO] Oooo 
oloo (too 
l1too tool 
Lto] 0000 
OVUolloo 
Ol,a0000 
1lolOO100 
1ol{ 1 0o]| 
1100 Jo00 
looo 0100 
Olld°0000 
00100000 
1010 0000 
Ilol Loot 


[101 0000 


loollooo 
O1L0°000 
\100}|000 
11000000 
[Lol ooo0o 
1O1O100\ 
O(|0%000 
00100000 
oo0O lClo 
CooOololo 
©0000 [oI°o 
Cooelole 
{oooolol 
0010 0000 
Oooo ole} 
O\leOo000 
01001000 
Stree ocee 
Stoo-coce 
C1Looeece 
C106 C660 
©0010 0000 
Oto 1000 
Ool10 1oel 
1o10 1900 
tot{ lool 
lolo Of0o0 
loo| tool 


1100 1000 
1000 01 CO 
OL 0000 


onloott 

{oo| oloo 

Oo000000\ 
LEUltt1o 
©o0o01l0000 
00000000 
©6606000 
© 100000| 
Ooo0cooll 
Lo1rootrt 
O100 | 10[ 
Ooo0 ool 
pol ool1o 
ool orl 
ooooooll 
1 10°0ldO 
OLCOOlll 
eoo°boll 
(CCL Tot 


IVIL LITO 
60000000 


tril o 


OO][1 0000 
00000000 
JT LOLoo| 
o°0000Il0 


00010000 
TELL OlOO 
00600000 


Oollt Loot 


{itt itol 
ool lool 
Lirereot 


oloololo 
C1rooclolo 


oO toololo 
Oloololo 
C1cColoco 


COoCOLll[ 


LtLlolool 
PEGE CO 
00 000000 


tren illo 


1 000 Ooo] 
l09CC00O| 


(000000 | 
1000 000| 
11Oo00e00 


loooqco| 


1o00000[ 


1000 000| 


00000000 


11009000 


toco000[ 


loo00000| 


loccooo| 


10000001 


looccool[ 


1000000[ 


(LO0O00O 


$ 8173 ware. LDA #$0¢ 
B75 STA $FE 
8177 LDA $FC 
$179 TSR $8i58 
$i7¢ LDA $F6 
SITE IsR $3iSB 
$\€1 opi LDA #$¢D 
$133 TSR $B1GA 
BIG ORTY LOY #999 
SI8F LDA $C9d¢,Y 
$198 ISR $FFDA 
RISE INY 
SIF CMP #¢¢D 
Bia BNE $FS 
B\93 RTS 
Zia4y owe.tty LbY 440g 
B19G JSR $FFCF 
8194 STA $C69¢, Y 
B\Ic INY 
S19D CMP #$¢D 
SIMF BNE $F5 
SiAl STA $C899,Y 
SAY TMP $FFDX 
SIA7 set ar. JSR $31H4C 
S\AA STA $FC 
SIAC Isk $84 
SIAF STA $FB 
SIBl RTS 
BIBX Ro.ren LOX #19 
S\BY LoY #$¢¢ 
$ RBC LOA (478), Y 
BIB 8 ISR $4158 
ZIBB TSR $F1DB 
SIBE DEX 
SIBF BNE $F3 
Bic} TMP $8181 
Zicy WRNEM LOY $FE 
SICG Lod $cod¢,y¥ 
BICF CMP ¥4¢D 
SICB BNE $91 
Sled RTS 
SICE IsR $84 
B1D\ LOY #340 
BIDS STA ($F8), Y 
BIDS JSR $RIDB 
B10g IMP $BICH 
BIDB wer CLO 
aha LDA $FB 
SIDE Ave #$¢1 
SIED STA $FB 
BIER LOA $Fc | 
SIEY ADC 4409 
BIEG STA $Fc 
SIEZ RTS 
BSIEY HEKDIG $3¢ 
$3! | 
$32 | 
$33 | 
34 | 
35 
36 
ie | 
$33 


D8 


58 38i 
58 38 


GA 8! 


cg 
FF 


FF 
eg 


Cg 
FF 


4c $I 


4C 8 


31 
8\ 


$1 


cg 


$1 


%\ 
3I 


lo1o loot 
loooolol 
loro olol 
00|00000 
loloolol 
OO|o 0°00 
1olo joo! 
0016 0000 
1010 0600 
fort loot 
00100000 
|tlooltooo 
1100100} 
tlo[ 0000 
O110 0000 
1010 0000 
0010 9 900 
[ool loot 
1100 1000 
[Loolool 
{1010000 
1OOl| 1 ool 
0100 1100 
0010 0000 
loooolel 
OOl0 0000 
looc0olo| 
O1lL00000 
{oOlo 0010 
1016 0000 


lotloool 
©0l00000 
©0100000 
11001010 
1{ O| C000 
OClooltoo 
Lolo C100 
lott lool 
lLoo lool 
[1 ol 0000 
©1100 0000 
0010 0000 
1019 C000 
lool Ooo, 
O0O1\0 0000 
C100 L100 
©00| 1006 
loiooiol 
O1LO lool 
1000 Olo\ 
lOlo Clot 
O\lo lool 
loooojot 
O110 9000 
Ool(l C000 
Ooll Cool 
OO! 6010 
Coll colt 
Coll oloo 
OOIl O1o| 
Oo1l o1lo 
Oo1ont 
Oot tooo 


09000000 
Ul te CEO 
Ltt te loo 
olol loll 
trp Lotl 

Olol lott 

cooollol 

CLIO Lolo 
06000000 
00006000 
L1olL O0lo 


Qo°00 I10l 
(titolo 


©0000000 
ploortit 
09000000 


Cdoollol 
(LLL olol 
O0000000 
1(O@looto 
Oloolloo 
rit lloo 
0100 1100 
CItLtlotl 


000| 9°00 
00000000 


{CIELO 
Olof roll 
(lof toqt 


thet oor 
1006 ©c0\ 
Liititto 
©000 0000 
Cooo|lol 
lToloFor-JoYoo | 


Olco 1100 
20000000 
Luetllott 
trol totl 
llo 9 C100 


(LT LLOll 
CcCC°CC~CO| 
(ttrlouy 
(ltl t10eo 
00000000 
Hit ttoo 


i aa. 


}000 0o0| 


loco o00( 


1000 coo| 


1100 0000 
CL EEURhy 


Le, i Ve | 
{1000000 


tloooGo0o 
Terepaet 
looooool 


10a0 Cool 


| 000 000| 
tooocco! 


l0co Cool 


\looco°ce 


1oo0coo| 


lo0o CGO| 
looc ooo! 


OCll\iool 
O1C0000( 
O|oo001o 
Olooool( 


O100 0100 
Oloool\ol 


OLOoollo 


te onter it .. 


Cheatsheets and Chickenscratches 


| decided, while | was writing all this code by hand, | might as well 
also write out some stuff about 6502 programming that | can never 
remember when | need it. 


GSO2 CONDITIONAL BRANCHES 


THE OPERAND OF A CONDITIONAL BRANCH (IS A 
RELATIVE AppRESS, GIVEN AS A SIGNED BYTE 
ENCODED IN ‘Two’ COMPLEMENT. THE ADDRESS 
IS RELATIVE To “THE INSTRUCTION FoLLOWING THE 
BRANCH, THUS, -2 = $FE WiLL BRANCH To ITSELF. 


WHEN COMPARING SIGNED BYTES, CHECK THE 
CARRY FLAW To TEST FOR RELATIVE MAGNITUDE. 


LDA 
CMP 
Bec 


LDA 
cmp 
Bcs 


LDA 
CMP 
BEQ 
BCS 


FOO 
#$96 
FOO_LLT_6G 


BAR 
t$ BG 
BAR. GTE_6 


BAZ 
#406 
BAZ_E€Q_6 
BAZ_GT_¢ 


TWO TECHNIQUES FoR 
SHORTENING MACHINE CODE. 


1. FALLTHROUGH 


FOO: BLAH BLAH 


FOO: 
BLAH BLAH 
IMP BAR —_ » 

BAR: 


BAR: BLAH BLAH 
BLAH BLAH 


a. TAIL CALL 


Foo: BLAH Foo: BLAH 
BLAH = » BLAH 


JMP BAR 


EASY To REMBMBER RUT EVEN EASIER To Look UP... 


8 
q 
A 
B 
G 
D 
E 
= 


Sketches of the design and code for the machine-language monitor. 
It was basically written three times; once in pencil, once with a 
ballpoint pen, and the final version (not shown here, coming soon!) 


with fineliners. 


| 


| READ Live. 
Lf Ror UY 


Fi : 
wih A? 


No 


DARSE. ees 
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A better front-panel simulator 


One thing that disappointed me slightly during The Warm-up was that 
the simulated front-panel loader was not terribly realistic. It lets you 
backspace to erase bits you've typed in, and it leaves a “paper trail” 
of values you’ve entered, on the screen. It occurred to me that it 
wouldn’t be too difficult to write something that simulates a front 
panel better, so that is just what | did. 


The front-panel simulator below works a lot like the 1802 


Membership Card front panel (see Loading the code for more details 
on that.) 
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The screen shows an approximation of 8 LEDs and 8 SPST switches 
that would be connected to the 8 data lines on a real front panel. 


The keys on the bottom row of the keyboard move each switch down; 


the keys in the 2nd-to-bottom row move each switch up. (In an effort 
to be more realistic, they are not toggled by a single key.) 


Pressing Return causes the binary value selected by the switches to 


be written to the current address in RAM. That value is then reflected 
in the LEDs. 


Other simulated buttons (not show in the Ul) are 


e “=, which advances the address by one (you typically press 
this every time you are happy with the current byte you have 
written, ) 

e ‘& which resets the address to the beginning of memory 
(which can be used to review the bits you’ve entered by 
stepping through them with *=" and watching the LEDs), and 

e ‘!’ to execute the machine code at the current address. 


| plan to use it to enter the machine-code monitor program I’m writing 
(more on that in a future post.) 


I'll put the code for this front-panel simulator (and other code from 
this project) in a repository on Github at the end of the month (or 
earlier, if someone requests it.) 


The Warm-up 


BEFORE EMBARKING ON OUR MAIN PROJECT, 
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All written! Now, to load it (see “Loading the code” for details on 


this)... 
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Loading the code 


The most “cheating” part of this project will be avoiding the actual 
loading of the machine code into an actual machine, so | feel that 
should describe what it would actually be like, in the real world. 


For the sake of example, assume we've already written a 
programming environment — the one that we want to put into our 
computer, a computer that doesn’t have any sort of programming 
environment on it yet. Assume we've written this program by hand, 
on paper... and that we've already converted it all into machine code. 
The first line of it might look something like this: 


ADDRESS INSTRUCTION HEX ti NARY 


$Ps¢¢e LDA #32¢ AY O¢ 0101001 CcCoC00OCO 


...followed by many, many more lines. 


There are, of course, many ways to get a program into a computer — 
that is, into its memory. 


In the modern world, we would just open a text editor and start typing 
in the program. But think of how much hardware and software is 
required to support this! Decoding the keystrokes from the keyboard 
is not terribly complicated, but displaying characters on a video 
display is quite another matter. And never mind that the text editor is 
yet another program that someone had to write (and get into the 
computer somehow. ) 


I'll describe a much more primitive method here. 


Glossing over some of the details, a typical memory circuit has a 
number of address lines, a number of data lines, and a read/write 
gate. For example, a 64 kilobyte bank of memory might have 16 
address lines and 8 data lines. 


To locate a byte in memory, you put a binary-encoded version of its 
address on the address lines. To read that byte, you set the 
read/write gate to “read” and look at what value is on the data lines. 
To write a byte, you instead put the value you write onto the data 
lines, and set the read/write gate to “write”. 


Normally, the CPU is doing all this memory-access. But all these 
lines, they’re just wires with voltages on them. So you can do all 
this reading and writing by hand, using switches. 


In fact, the front panels of some of the earliest home computers had 


switches and lights on them for just this purpose, like the Altair 8800 
shown here: 


And in the absence of any other hardware, this was how you 


programmed it. You flipped the switches to represent the binary 
value you wanted to write into memory, and pressed a button to write 
it. 


| was going to walk through this process and ask you to imagine it, 
but @retrochallenge pointed out the 1802 Membership Card, which 
is a kit based on the COSMAC ELF, which, like the Altair 8800, was 
programmed with front panel switches. 


So instead, you can read the instructions for 1802 Membership Card 
code loading, or watch this video to see what loading code this way 
is like: 


And now that I’ve shown you this, there is something I'd like to point 
out... 


There’s a simple improvement over switches that’s fairly obvious 
when you think about it a bit. Instead of manually changing the 
switches with your fingers, why not have some kind of mechanical 
contrivance which sets the switches according to a pre-arranged 
pattern? 


Indeed, this technology exists, and you have probably heard of it: the 
punched card. 


| [NTEGER*®4 TYPPARs TYPANTs SNOGLE(2>s SORDEN(2>sNENGL, 
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At its simplest, a punchcard reader is barely any more complex than 
front-panel switches. When a card is inserted, switch contacts close 
where there are holes in the card, and stay open where there aren't 
holes. And then that bit pattern gets written to memory. As a bonus, 
the punched card serves as a record of the bytes that were written to 
memory, and can be re-used. 


If anything, it’s the technology of card punching that’s more 
advanced. In the example above, the card puncher has printed at the 
top, by what looks like a dot-matrix printer, the characters for the 
values it has punched holes for below. But that’s certainly not 
necessary; in principle, you could punch out the holes by hand, using 
a hole-punch. 


Simulating loading the code 


OK! Now that I’ve imparted to you what it’s like, I’m going to explain 
why I’m going to take the liberty of not actually doing it this way, and 
how | plan to fudge it :) 


This project is primarily about making a new software development 
environment (using the existing “software development environment” 
of pen and paper) to be used on a computer. The act of actually 


putting it there is secondary — still important for context, of course, 
which is why | described it in detail. 


Also, if all the computer has is front-panel switches and lights, then 
maybe putting a programming environment onto it isn’t the most 
useful thing you can do. Yes, it’s easier to write a program in BASIC 
instead of in machine language, but if you still have to enter your 
BASIC program, byte by byte, in binary, using switches or by 
punching holes, that’s still quite a bottleneck. 


My point here is that front-panel switches and punchcard readers can 
load code into a computer directly, at the hardware level. Most other 
input devices — keyboards, serial ports, etc. — can't do that; they’re 
too general-purpose. To load code, they would need to work in 
concert with some software routines that interpret the input they 
receive. 


Ah, but a programming environment could contain such software 
routines! In fact, if the purpose of a programming environment is to 
make it easier to develop software, then arguably it should let you 
use these easier-to-use, general-purpose input devices for this task. 


So, since the hardware for this project is going to be emulated 
anyway, what | would like to do is assume that the machine has, 
along with simulated front-panel switches, some kind of simulated 
teletype attached to it. 


We'll enter the programming environment into the computer by the 
front-panel switches. But the programming environment itself will use 
the simulated teletype to interact with the user. 


The actual architecture will probably look something like this: 


e An emulator for a 6052-based computer (probably a 
Commodore 64). 


e A little program that simulates front-panel switches, reading in 
strings of binary digits like 00000100 from the C64 keyboard 
and writing values (in this case, 4) to successive locations in 
memory. 

e A pair of machine-language subroutines for reading a line of 
text from, and writing a line of text to, the simulated teletype. In 
principle, we could write these subroutines so that they 
actually talked to a teletype. In practice, they'll probably be 
implemented with calls to C64 KERNAL routines for reading 
from the keyboard and writing to the screen. 


If that seems rather “cheaty”, well... | agree, it’s not ideal, but I’ve 
only got a month to finish this :) 


Since this might be the last blog post before | begin, I'll mention a few 
other things you can expect from this project. 


e The program will be designed, programmed, and hand- 
assembled, on paper. 

e Updates to this blog will consist mainly of photos or scans of 
those papers... | won't be writing posts about the design. 

e | will have a hardcopy of the Commodore 64 Programmer’s 
Reference Guide which | will feel free to consult, but I'll try very 
very hard not to consult the Internet. 

e | might do a little warmup first (like, “echo the lines you type in”) 
before starting on the programming environment proper. 

e The programming environment will probably be very similar to 
FORTH. | will definitely be trying to keep it small (I will have to 
enter all these bytes, in binary, at the end!) while aiming to 
make it easier to program with than assembly. 

e The programming environment won't use any features of the 
C64 except for those two KERNAL routines to simulate a 
teletype. 


e | won't hesitate to save the emulator’s state while entering the 
code, so | don’t have to do it all in one sitting. But... I'll try very 
hard not to abuse that feature, to e.g. “undo” entering wrong 
code. (This suggests the programming environment should 
contain some kind of debugger...) 


And, er, that’s it! Can’t wait to start! 


Why write it by hand? 


In the previous post, | outlined the project that Cat's Eye 
Technologies plans to do for RetroChallenge 2015/07: writing a 
programming environment by hand. 


But | didn’t go into why | chose this project. 


The reasons are fairly simple. In 2015, and in fact for decades now, 
software for computers has been developed almost exclusively with 
the aid of computers. 


The sheer pervasiveness of this situation might almost lull you into 
an impression that it has always been done this way. 


But, even if you don’t know the history, you can logically reason that 
it can't possibly have always been done this way; in order to develop 
software using a computer, there needs to be software on that 
computer first. It’s a chicken-and-egg problem. 


The very first computers must have had no software on them, and 
the software for them must have been developed without using a 


computer, and then loaded into the computer... somehow. Only after 
that point could the computer be used to develop more and newer 
software for itself. 


This situation, incidentally, explains the name of this blog. Getting 
over this chicken-and-egg complication is called bootstrapping, 
after the mythical idea that one might reach down and, grabbing hold 
of one’s own boot-straps, lift oneself off the ground. The concept 
shows up in several places in computer engineering, particularly in 
compiler development, but even in the common process of powering 
on a computer: we say the computer “boots”, which is just a 
shortening of “bootstrap”. 


Meanwhile, “zero” refers to the fact that there is no software on the 
computer yet, and suggests an origin point; we are starting with 
nothing. (OK, even if that’s not absolutely true, let’s say we're trying 
to get as close to the “zero point of software development” as 
reasonably possible.) 


Or to put it another way: pen and paper is also a programming 
environment. 


And, since it’s so much easier to develop software using a computer, 
it's rather a foreign environment these days. So let’s revisit it, lest 
habituation to screens and keyboards dulls our imagination! 


For the next post, | hope to write a bit about the part where the code 
is actually loaded into the computer (since that’s the part we’re going 
to fudge the most, so I’d like to impart what it’s like, the best | can.) 
And while July is underway, | hope to be able to update the blog 
regularly with photos of the handwritten materials. Stay tuned! 
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